🗒️ Description

Adds a consume enginex simulator that reuses client instances across tests sharing the same pre-allocation state. This simulator significantly reduces test execution time compared to consume engine by avoiding per-test client startup overhead.

Includes basic pytest-xdist support via --dist=loadgroup, with further optimizations planned in subsequent PRs.

Architecture

The enginex simulator groups tests by pre_hash (hash of genesis + pre-state). Tests in the same group run against a single client instance instead of starting/stopping per test.

New Files

Modified

Execution Flow

1. Collection: pytest_collection_modifyitems counts tests per group, sorts by pre_hash.
2. First test in group: Starts client, registers with manager.
3. Subsequent tests: Reuses existing client (skips FCU to keep at genesis).
4. Last test in group: mark_test_completed triggers client shutdown.
5. Session end: Cleanup any remaining clients.

Fixture Chain

flowchart LR
    subgraph "Per Group (cached)"
        PAG[pre_alloc_group] --> CG[client_genesis]
        PAG --> GH[genesis_header]
        CG --> BG[buffered_genesis]
        BG --> CF[client_files]
    end

    subgraph "Client (reused)"
        CF --> C[client]
        C --> ETH[eth_rpc]
        C --> ENG[engine_rpc]
    end

    subgraph "Per Test"
        TC[test_case] --> F[fixture]
        F --> P[payloads]
    end

    subgraph "Test Execution"
        GH --> TEST[test_blockchain_via_engine]
        ENG --> TEST
        P --> TEST
    end

Testing

For testing, use this custom release which keeps tests marked as @pytest.mark.slow in the same pre-alloc group as their non-slow counterparts (greatly reduces the number of groups):

https://github.com/danceratopz/execution-specs/releases/tag/v0.1.0a1

# Dev mode (requires hive --dev backend)
uv run consume enginex --input=https://github.com/danceratopz/execution-specs/releases/download/v0.1.0a1/fixtures.tar.gz -v -s -k "/shanghai/ and (fork_shanghai or fork_cancun) and push0"

# With parallelism
uv run consume enginex --input=https://github.com/danceratopz/execution-specs/releases/download/v0.1.0a1/fixtures.tar.gz -n 4 -k "(fork_shanghai or fork_cancun) and push0"

🔗 Related Issues or PRs

N/A.

✅ Checklist

• All: Ran fast tox checks to avoid unnecessary CI fails, see also Code Standards and Enabling Pre-commit Checks:

  uvx tox -e static

• All: PR title adheres to the repo standard - it will be used as the squash commit message and should start type(scope):.
• [ ] All: Considered adding an entry to CHANGELOG.md. skipped
• All: Considered updating the online docs in the ./docs/ directory.
• All: Set appropriate labels for the changes (only maintainers can apply labels).

Cute Animal Picture